Version and validate the agent-context schema (6.2.2)#349
Conversation
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
87ea9ab to
90cd983
Compare
…6.2.2) Draft execution plan for roadmap item 6.2.2. Covers schema shape and version guard tests in ortho_config, generator determinism and a default-display policy in cargo-orthohelp, three minimal golden fixtures (simple, enum, nested), the optional inclusion of agent-context in `--format all`, and the agent-context compatibility policy documentation. The plan is informed by a community-of-experts design review and surfaces open decisions about the exact v1 wire shape for approval before implementation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Roadmap 6.1.2 (PR #340) merged to main during this branch's draft and was picked up by a rebase. It added a reusable nested clap tree (NestedFixtureConfig) to the existing orthohelp_fixture crate and established the --root-type multi-root convention, but covers only IR, roff, and PowerShell — not the agent-context format. Revise the plan to reuse that infrastructure instead of authoring new fixture crates: reuse NestedFixtureConfig (nested) and FixtureConfig (enum, the default root), and add only a minimal SimpleFixtureConfig root, each golden selected via --root-type. Narrow Risk 1 (the agent-context recursion is now the only unexercised part), reduce scope (one struct plus locale keys, no new workspace members), and add a 6.2.2-vs-6.1.2 render-assertion fence. A revision note records the change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Update the 6.2.2 ExecPlan to record D1, D2, D3, and D5 as accepted, and choose the D4 pre-1.0 enum casing change. Keep Milestone 1 and the compatibility-policy work aligned with the new decision to standardize agent-context enum wire strings to `snake_case` before locking the schema.
Record the execution start for the 6.2.2 ExecPlan, including the current branch, PR title, and Lody session context.
Standardize agent-context enum serialization on `snake_case` before locking the v1 wire contract. Add schema guard tests for the version and kind pins, comprehensive wire shape, unknown-field tolerance, and variant-exhaustive enum wire values. Record the Milestone 1 red/green evidence and gate results in the ExecPlan so later milestones can rely on the locked schema baseline.
Add generator-side guards for the agent-context transform before expanding the end-to-end golden matrix. The adapter now normalizes unstable proc-macro token spacing in default displays, so default-bearing goldens are not churned by `proc_macro2` formatting changes. The new tests prove deterministic pretty JSON output for the same bridge IR and pin nested command projection through a two-level command tree. The existing agent-context golden is re-baselined for the approved default-display normalization.
Cover agent-context generation for the three root shapes named by the plan: a minimal flat scalar root, the existing enum-bearing fixture root, and the nested command-tree fixture from 6.1.2. The golden test is now parametrized over root types and snapshots each shape independently. Add a nested BDD scenario that asserts generated command paths include both a top-level subcommand and the deeper admin audit path, proving the behaviour layer exercises nested agent-context output rather than only checking that JSON was written.
Treat `--format all` as additive over the now-locked agent-context contract by writing `agent-context.json` alongside the existing IR, man-page, and PowerShell artefacts. This fulfils the previous deferral without changing the legacy output paths or assertions. The all-formats BDD scenario now checks that the compact agent-context document is emitted in addition to the existing generated outputs.
Record the v1 compatibility rules, defaulting policy, and agent-context inclusion in format-all documentation.
Record the skill_manifests default added on main in the simple and nested agent-context snapshots after rebasing onto origin/main.
57c9bd7 to
fb3ff68
Compare
There was a problem hiding this comment.
Gates Failed
Enforce advisory code health rules
(2 files with Large Method, Large Assertion Blocks, Code Duplication)
Our agent can fix these. Install it.
Gates Passed
5 Quality Gates Passed
Reason for failure
| Enforce advisory code health rules | Violations | Code Health Impact | |
|---|---|---|---|
| tests.rs | 2 advisory rules | 10.00 → 8.68 | Suppress |
| steps_agent_context.rs | 1 advisory rule | 10.00 → 9.39 | Suppress |
Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.
|
|
||
| assert_snapshot!(json, @r###" | ||
| { | ||
| "schema_version": "1", | ||
| "kind": "example-cli.agent_context", | ||
| "package": "example-cli", | ||
| "commands": [ | ||
| { | ||
| "path": [ | ||
| "example-cli", | ||
| "list" | ||
| ], | ||
| "summary": "List configured resources.", | ||
| "canonical_verb": "list", | ||
| "inputs": [ | ||
| { | ||
| "name": "format", | ||
| "long": "format", | ||
| "value_type": "string", | ||
| "required": false, | ||
| "default": "json", | ||
| "enum_values": [ | ||
| "json" | ||
| ] | ||
| } | ||
| ], | ||
| "output_modes": [ | ||
| "json" | ||
| ], | ||
| "interaction_mode": "non_interactive", | ||
| "mutation_effect": "read_only", | ||
| "async_submission": { | ||
| "mode": "submit", | ||
| "noun": "job" | ||
| }, | ||
| "delivery_route": { | ||
| "supported": true, | ||
| "target": "file" | ||
| }, | ||
| "pagination": { | ||
| "limit_input": "limit", | ||
| "cursor_input": "cursor" | ||
| }, | ||
| "examples": [ | ||
| { | ||
| "command": "example-cli list --format json", | ||
| "output_mode": "json" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "profiles": { | ||
| "supported": false | ||
| }, | ||
| "feedback": { | ||
| "supported": false | ||
| }, | ||
| "policy": { | ||
| "agent_native": "warn" | ||
| }, | ||
| "skill_manifests": [ | ||
| { | ||
| "id": "example-list", | ||
| "path": "skills/example-list.md", | ||
| "manifest_schema_version": "v1", | ||
| "commands": [ | ||
| { | ||
| "path": [ | ||
| "example-cli", | ||
| "list" | ||
| ], | ||
| "flags": [ | ||
| "format" | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| "###); | ||
| } |
There was a problem hiding this comment.
❌ New issue: Large Method
agent_context_json_snapshot_covers_wire_contract has 83 lines, threshold = 70
Summary
Implements roadmap item 6.2.2 — Version and validate the agent-context schema.
This locks the v1 agent-context wire contract, broadens generator coverage, and
updates the compatibility documentation now that
agent-context.jsonis part of--format all.What changed
snake_casebefore the v1contract is locked, including the intentional
read_onlyre-baseline.ortho_config: comprehensive wire snapshot coverage,version/kind pins, variant-exhaustive enum tests, unknown-field tolerance, and
documented null-versus-omitted optional-field behaviour.
cargo-orthohelpagent-context generation with default-displaynormalization, deterministic transform property coverage, and nested command
structural assertions.
fixture roots, plus BDD coverage for nested command paths.
cargo orthohelp --format allwriteagent-context.jsonbeside IR,man-page, and PowerShell artefacts.
docs/agent-native-cli-design.md,updated ADR-003/users/developers/cargo-orthohelp docs, and ticked 6.2.2 in the
roadmap and execplan.
Validation
Milestone gates were run before each CodeRabbit review. Final validation:
make check-fmtmake typecheckmake lintmake testmake markdownlintmake nixiecoderabbit review --agent(findings: 0)References
docs/execplans/6-2-2-version-and-validate-the-agent-context-schema.md